PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / comstr.exe / READ.ME < prev next >

Wrap

Text File | 1992-12-01 | 12.3 KB | 390 lines

Patrick Reilly CIS: 70274,161 This file represents an upgrade for the older COMST1.ZIP. That file had problems. Besides being cryptic and only a streambuf-derived class, there was a bug in the combuf::extractc() method. This has been fixed in this version. As an addition, I've included a 'wrapper' iostream-derived class for people not overly familiar with the C++ stream classes. I've included manipulators for setting protocol (baud, parity, etc). Also new is this readme file! Description: struct ComDef ------------------------------------------------------------------------- This structure is used internally by combuf to keep track of who owns what port, etc. In general, you can ignore it. struct CommProtocol ------------------------------------------------------------------------- This structure encapsulates all the protocol settings for a port: baud rate, number of bits, parity, and stopbits. It is accepted as an argument to combuf::setParams(), and exists mainly for people wanting to directly play with combuf. class combuf ------------------------------------------------------------------------- This is the heart and sole of serial streaming. The combuf class is derived from streambuf, and handles the intricacies of serial communication. Methods ------- combuf( char *s, int i, int o ) constructor This sets up an unopen buffer (not attached to any serial port), with the input buffer at s[0]..s[i-1], and the output buffer at s[i]..s[i+o-1]. Unlike most streambufs, combuf actually uses two seperate areas of its internal buffer - an input part, and an output part. This is because you really don't want to mix the two: you want input to be inserted by the serial port (and extracted by your code) and output (inserted by your code) to be extracted by the serial port. combuf() constructor This sets up an unopen buffer with no internal buffer. Note that you will not be able to use (open) this until a call is made to setbuf(): combuf requires an internal buffer (does not operate in unbuffered mode). ~combuf() destructor Performs housekeeping (flush/close) and destroys the combuf. streambuf *setbuf( char *buf, int sz ) Since combuf actually uses two areas of a buffer, this method just calls setbuf( buf, sz/2, sz/2 ). combuf *setbuf( char *buf, int isz, int osz ) This sets the internal buffer input area to buf[0]..buf[isz-1] and the output area to buf[isz]..buf[isz+osz-1]. int underflow() This method is called whenever you want to extract from the combuf but the serial port hasn't put any data in it. It will wait the timeout period for a char to appear: if so, everythings fine. If not, returns EOF which will signal the owning stream to set an error flag. int do_sputn( char *s, int n ) This method puts your output into the buffer and handles serial- related issues (priming the pump) to make sure it gets sent. int overflow(int) Called whenever the internal buffer is full and you still want to send characters. Flushes the buffer and puts the char in there. It checks for timeout errors, and will return EOF if one occurs, which will signal the owning stream to set an error flag. void setPort( int p ) 'Opens' a serial port for use. The port number (p) MUST be in the range 0 (COM1) to 3 (COM4). void setTimeout( long t ) Sets the timeout period to t, where t is in 1/100ths of a second. Note that, though the argument is in 1/100ths of a second, the actual resolution of the timeout timer is in +/- 55mSec. It always rounds up, so setTimeout(1) will set timeout_ to 1, NOT 0. void setInterCharDelay( long t ) Sets the intercharacter delay to t, where t is in 1/100ths of a second. The intercharacter delay is the amount of time paused between sending consecutive characters; for some systems (and many modems), some delay is required between the chars. void setInterLineDelay( long t ) Sets the interline delay to t, where t is in 1/100ths of a second. The interline delay is the amount of time paused after sending a carriage return (ascii 13). Some systems are line-oriented (ie they buffer a line, then process it) and so require a delay after a line is sent. void setOption( int bit ) Sets options flags. Valid bits are: HW_HANDSHAKE (use hardware handshaking: not currently implemented), SW_HANDSHAKE (use software handshaking (XON/XOFF): not currently implemented), and WAITFORECHO (pause after sending a char until its echo is received: not currently implemented). void clearOption( int bit ) Clears option flag (see setOption() for flags). void setBaud( long b ) Sets the baud rate to b. Must be in the range 50 <= b <= 115200. Note that the baud rate is changed ONLY if the port is open. void setParity( int p ) Sets the parity to p (one of: combuf::none, combuf::odd, combuf::even). Note that the port must be open for the parity to change. void setBits( int b ) Sets the number of bits in the protocol: must be 6 <= b <= 8. Note the port MUST be open for the bits to change. void setStopBits( int b ) Sets the number of stop bits in the protocol: must be 1 <= b <= 2. Note that the port MUST be open for the stop bits to change. void setParams( CommProtocol& p ) Sets the baud, bits, parity, and stopbits as contained in p. Note that the port MUST be open for the changes to occur. void assertDTR() If the port is open, asserts the DTR (Data Terminal Ready) signal. THIS IS NOT DONE AUTOMATICALLY BY SETPORT()! Note that a modem will ignore you unless you assert DTR. void unassertDTR() If the port is open, unasserts the DTR signal. This will disable communications with a modem (if it was off-hook, it will hang up). int status() If timeout, line, or modem errors have occured, they set an internal status flag. Calling this method will return the status, then clear it. int extractc() Used by the ISR (interrupt service routine) to get the next char to be sent out the serial port. int insertc( int ch ) Used by the ISR to insert ch (incoming byte) to the buffer. unsigned long timeToTicks( unsigned long t ) Converts t (1/100ths of a second) to system ticks (18.2 per second). void assertToPort( int offs, int mask ) Used internally by combuf to assert (set) bits to a port. void unassertToPort( int offs, int mask ) Used internally by combuf to unassert (clear) bits to a port. void interrupt far handler0x0B(...) This is the ISR that services interrupts for COM2/4. void interrupt far handler0x0C(...) This is the ISR that services interrupts for COM1/3. void handleIRQ( int port, int cause, int data ) This is the method that is called when an interrupt on the combuf's port occurs. Members ------- ComDef def[4] Holds information for each port (COM1,2,3,4). enum ParityType { none, odd, even } Used for the argument to setParity(). int offs_ The offset into def for this combuf. If EOF, means this combuf is closed. Otherwise (0..3) this combuf is open. int errFlags Holds error flags; returned/cleared by status(). int options Holds the option flags. Bits are set with setOption() and cleared with clearOption(). int inSize Size of the input buffer. unsigned long timeout_ Timeout time (in ticks). unsigned long ibdelay_ Intercharacter delay time (in ticks). unsigned long ildelay_ Interline delay time (in ticks). class comstream ------------------------------------------------------------------------- This class is derived from iostream and presents an iostream 'wrapper' for combuf. Methods ------- comstream() constructor Initializes a comstream with no buffer. Note that you can't use this stream until a call to rdbuf()->setbuf() is made. comstream( char *b, int i, int o ) constructor Initializes a comstream with an input buffer at b[0]..b[i-1] and an output buffer at b[i]..b[i+o-1]. ~comstream() destructor Does nothing. combuf *rdbuf() Returns a pointer to the combuf attached to this stream. void open( int p ) Opens port p for use, p must be 0..3. Also calls buf.assertDtr() to assert the DTR signal. void close() Closes (and flushes) the stream. Members ------- combuf buf The combuf associated with this stream. Manipulators ------------ baud( long b ) Sets the baud rate to b. Stream must be open. Example: comstr << baud(2400); bits( int ) Sets the number of bits in the protocol. Stream must be open. Example: comstr << bits(8); parity( int ) Sets the parity. Stream must be open. Example: comstr << parity(combuf::none); stopbits( int ) Sets the number of stop bits. Stream must be open. Example: comstr << stopbits(1); timeout( long t ) Sets the timeout period in 1/100ths second. Example: comstr << timeout(300); // 3 seconds intercharDelay( int t ) Sets the interchar delay in 1/100ths second. Example: comstr << intercharDelay(2); Note: this states 2/100ths second, but the real delay is 110mSec +/- 55 mSec. interlineDelay( int t ) Sets the interline delay in 1/100ths second. Example: comstr << interlineDelay(5); ------------------------------------------------------------------------- This is still a fairly simple set of classes - its made to be built on. I didn't bother to include the HW_HANDSHAKE option because most systems ignore Rts/Cts. Implementing the SW_HANDSHAKE option (XON/XOFF) is non- trivial: XOFF has to signal extractc() NOT to extract chars when XOFF has been received; insertc() upon receipt of XON has to disable this and force a send if there's data in the output buffer (to 'prime the pump'). WAITFORECHO is also non-trivial. For use in telecommunications, abilities need to be added to support block transfers (XMODEM, etc). Also, OOP adds overhead that is undesirable for true telecomm, as it will slow things down for baud rates above 2400. Still, for simple apps, this class should be handy. Pat Reilly 70274,161 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 4,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394